PATH Hardware Documentation > Device Managers and Drivers > ATA Devices > ATA Device Software Guide

The ATA Parameter Block

This section defines the fields that are common to all ATA Manager functions that use the ATA parameter block. The fields used for specific functions are defined in the description of the functions to which they apply. You use the ATA parameter block for all calls to the ATA Manager. The ataPBHdr data type defines the ATA parameter block. 

ATA Manager 3.0 defines ATA parameter block version 3, which is required for the specification of ANSI ATA-2 compliant transfer timings, and DMA timing in particular. ATA Manager 4.0 and later support ANSI ATA-2 and ATA-3 compliant data transfer timings. Parameter block versions 1 and 2 are still supported, but full use of version 4.1.1 or later is recommended when the best data transfer performance of the device is required.

The parameter block includes a field, ataPBFunctionCode, in which you specify the function selector for the particular function to be executed; you must specify a value for this field. Each ATA function may use different fields of the ATA parameter block for parameters specific to that function.

An arrow preceding the comment indicates whether the parameter is an input parameter, an output parameter, or both.

The following unique typedef identifiers are used in the ATA Manager parameter block and function definitions:

SInt8

   A signed 8-bit field

SInt16

   A signed 16-bit field

SInt32

   A signed 32-bit field

UInt8

   An unsigned 8-bit field

UInt16

   An unsigned 16-bit field

UInt32

   An unsigned 32-bit field

typedef	struct	ataPBHdr	/* ATA Manager parameter */
			/* block header structure */
{
	Ptr	ataPBLink;	/* Reserved, initiaize to 0 */
	SInt16	ataPBQType;	/* Type byte */
	UInt8	ataPBVers;	/* --> Parameter block */
			/* version number */
	UInt8	ataPBReserved;	/* Reserved */
	Ptr	ataPBReserved2;	/* Reserved */
	ProcPtr	ataPBCallbackPtr;	/* Universal completion*/
			/* routine pointer */
	OSErr	ataPBResult;	/* <-- Returned result */
	UInt8	ataPBFunctionCode;	/* --> Manager function*/
			/* code */
	UInt8	ataPBIOSpeed;	/* --> I/O timing class */
	UInt16	ataPBFlags;	/* --> Control options */
	SInt16	ataPBReserved3;	/* Reserved */
	long	ataPBDeviceID;	/* --> Device ID */
	UInt32	ataPBTimeOut;	/* --> Transaction timeout*/
			/* value */
	Ptr	ataPBClientPtr1;	/* Client storage Ptr 1 */
	Ptr	ataPBClientPtr2;	/* Client storage Ptr 2 */
	UInt16	ataPBState;	/* Reserved, init to 0 */
	SInt16	ataPBSemaphores;	/* Reserved */
	SInt32	ataPBReserved4;	/* Reserved */
} ataPBHdr;

Field descriptions

ataPBLink

This field is reserved for use by the ATA Manager. It is used internally for queuing I/O requests. It must be initialized to 0 before calling the ATA Manager and should be ignored upon return. This field should not be changed until the requested operation has completed.

ataPBQType

This field is the queue type byte for safety check. It should be initialized to 0.

ataPBVers

This field contains the parameter block structure version number. Values 1 through 3 are currently supported. Any values greater than 3 or a value of 0 result in a paramErr .

ataPBReserved

This field is reserved for future use. To ensure future compatibility, all reserved fields should be set to 0.

ataPBReserved2

This field is reserved for future use. To ensure future compatibility, all reserved fields should be set to 0.

ataPBCallbackPtr

This field contains the completion routine pointer to be called on completion of the request. When this field is set to 0, it indicates a synchronous I/O request; a nonzero value indicates an asynchronous I/O request. The routine this field points to is called either when the request has finished without error or when the request has terminated due to an error. This field is valid for any manager request. The completion routine is called as follows:

pascal void (*RoutinePtr) (ataPB *)

The completion routine is called with the associated manager parameter block in the stack.

ataPBResult

Completion status. This field is returned by the ATA Manager after the request is completed. The value in this field is invalid until the operation is complete. Refer to Table 4-1 for a list of the possible error codes returned in this field.

ataPBFunctionCode

This field is the function selector for the ATA Manager. The functions are defined in Table 3-2 . An invalid code in this field results in an ATAFuncNotSupported error.

ataPBPIOSpeed

This field specifies the I/O speed requirement for the ATA device. It is ignored in version 3.0 of the ATA Manager. The method for determining the I/O speed for version 3 of the ATA Manager is provided in the ATA_SetDevConfig function description.
For parameter block versions 1 and 2, this field specifies the I/O cycle timing requirement of the specified device. This field should contain the equivalent of word 51 of the identify drive data, as defined in the ATA-2 specification. Values 0 through 3 are supported by version 2 of the ATA Manager. See the ATA-2 specification for the definitions of the timing values. If a timing value higher than one supported is specified, the ATA Manager operates in the fastest timing mode supported. Until the timing value is determined by examining the identify drive data returned by the ATA_Identify function, the client should request operations using the slowest mode (PIO mode 0).
In ATA Manager version 1, the value in this field is always valid. That is, this timing value is used to complete the requested operation. With version 2, the value in this field is only valid if the CurrentSpeed bit is set to 0 in the ataFlags field. If the CurrentSpeed bit is set to 1, the manager uses the timing mode set previously by the ATA_SetDevConfig command for the device, or the default value, which is mode 0.

ataPBFlags

This 16-bit field contains control settings that indicate special handling of the requested function. The control bits are defined in Table 3-1 .

ataPBReserved3

This field is reserved for future use. To ensure future compatibility, all reserved fields should be set to 0.

ataPBDeviceID

A number that uniquely identifies an ATA device. This field consists of the following structure:

typedef	struct	/* Device ID structure */
{
UInt16	Reserved;	/* The upper word is reserved */
UInt8	devNum;	/* Consists of device ID */
UInt8	busNum	/* bus ID number */
} deviceIdentification;

Version 3. 0 of the ATA Manager supports two ATA devices per bus. The devices are physically numbered 0 and 1 respectively. Earlier versions of the ATA Manager used an unsigned 16-bit integer to specify the device number. In version 3.0 of the ATA Manager the devNum is used to distinguish between two devices on the bus specified by busNum . In systems with only one ATA device this value is always 0.

ataPBTimeOut

This field specifies the transaction timeout value in milliseconds. A value of zero disables the transaction timeout detection. If a timeout value is not set, the system may halt indefinately if the device fails to respond properly.

ataPBClientPtr1

This pointer field is available for application use. It is not modified or used by the ATA Manager.

ataPBClientPtr2

This pointer field is available for application use. It is not modified or used by the ATA Manager.

ataPBState

This field is used by the ATA Manager to keep track of the current bus state. This field must contain zero when calling the ATA Manager.

ataPBSemaphores

This field is reserved. To ensure future compatibility, all reserved fields should be set to 0.

ataPBReserved 4

This field is reserved for future use. To ensure future compatibility, all reserved fields should be set to 0.

Table 3-1 describes the functions of the control bits in the ataPBFlags field.

Table 3-1   Control bits in the ataPBFlags field 

Name	Bit	Definition
--	0-2	Reserved.
RegUpdate	3	When set to 1 this bit indicates that a set of device registers should be reported back on completion of the request. This bit is valid for the ATA_ExecI/O function only. Refer to the description on ATA_ExecIO for details. The following device registers are reported back: Sector count register Sector number register Cylinder register(s) SDH register
ProtocolType	5-4	These bits specify the type of command: 00 = Standard ATA 01 = Reserved 11 = ATAPI These bits indicate how the protocol should be handled for the command type. Setting the bits to ATAPI and providing a non-zero packet command pointer indicates that a packet command should be sent prior to any data transfers. For ATA command values of A0 and A1 hexadecimal, this field should contain the ATAPI setting. For all other ATA commands, the field must contain the ATA setting.
--	6	Reserved
UseDMA	7	When set to 1, this bit indicates the data transfer is to be via DMA. DMA transfers are only valid with version 3.0 or greater of the ATA Manager and on system hardware that supports DMA. DMA transfers to and from ATA devices use different command codes from the PIO transfers. The state of this bit must correspond to the command code.
SGType	9-8	This 2-bit field specifies the type of scatter gather list passed in. This field is only valid for read/write operations. The following types are defined: 00 = Scattergather disabled 01 = Scatter gather type I enabled 10 = Reserved 11 = Reserved When set to 0, this field indicates that the ioBuffer field contains the host buffer address for this transfer, and the ioReqCount field contains the byte transfer count.When set to 1, this field indicates that the ioBuffer and the ioReqCount fields of the parameter block for this request point to a host scatter gather list and the number of scatter gather entries in the list, respectively.
		The format of the scatter gather list is a series of the following structure definition:
typedef struct /* SG entry structure */ { uchar* ioBuffer; /* --> Data buffer pointer */ ulong ioReqCount; /* --> Byte count */ } IOBlock;
QLockOnError	10	When set to 0, this bit indicates that an error during the transaction should not freeze the I/O queue for the device. When an error occurs on an I/O request with this bit set to 0, the next queued request is processed following this request. When an error occurs with this bit set to 1, any I/O request without the Immediate bit set is halted until an ATA_QRelease command is issued. A status code of hexadecimal $717 is returned for subsequent asynchronous I/O requests until the I/O Queue Release command is issued. This permits the client application to examine the state at the time of the error. However, use with caution. When this bit is set to 1 and an error condition is not handled correctly, the system will hang.
Immediate	11	When this bit is set to 1, it indicates that the request must be executed as soon as possible and the status of the request must be returned. It forces the request to the head of the I/O queue for immediate execution. When this bit is set to 0, the request is queued in the order received and is executed according to that order.
ATAioDirection	13-12	This bit field specifies the direction of data transfer. Bit values are binary and defined as follows: 00= No data transfer 10 = Data direction in (read) 01= Data direction out (write) 11 = Reserved These bits do not need to specify the direction of the ATAPI command packet bytes.
ByteSwap	14	When set to 1, this bit indicates that every byte of data prior to transmission on write operations and upon reception on read operations is to be swapped. When this bit is set to 0, it forces bytes to go out in the LSB-MSB format compatible with IBM clones. Typically, this bit should be set to 0. Setting this bit has performance implications because the byte swap is performed by the software. Use this bit with caution. ATAPI command packet bytes are swapped when this bit is set to 1.
UseConfigSpeed	15	When set to 1, this bit indicates that the current I/O speed setting specified in the most recent call to the ATA_SetDevConfig command should be used to transfer data across the ATA interface. If a ATA_SetDevConfig command has not been issued since power on, then the default setting of PIO mode 0 and singleword DMA mode 0 are used.

Previous | Back Up One Level | Next | Show Frames | Hide Frames